# MicroPython语言参考

```{admonition} 本文引用的文件
:class: note

- [docs/docs/zh_CN/reference/index.rst](../../../products/mpython/reference/index.rst)
- [docs/docs/zh_CN/reference/glossary.rst](../../../products/mpython/reference/glossary.rst)
- [docs/docs/zh_CN/reference/repl.rst](../../../products/mpython/reference/repl.rst)
- [docs/docs/zh_CN/reference/constrained.rst](../../../products/mpython/reference/constrained.rst)
- [docs/docs/zh_CN/reference/speed_python.rst](../../../products/mpython/reference/speed_python.rst)
- [docs/docs/zh_CN/reference/packages.rst](../../../products/mpython/reference/packages.rst)
- `docs/docs/zh_CN/differences/index_template.txt`
- [esp32s3/docs/5_api/library/pythonStd/sys.rst](../../../products/mpython-s3/5_api/library/pythonStd/sys.rst)
```

## 产品概述
本参考面向需要在微控制器上编写MicroPython代码的开发者，聚焦以下目标：
- 明确MicroPython的语言特性与实现范围（以Python 3.4为基准）
- 梳理与CPython在标准库、类型和语言级功能上的差异要点
- 提供术语表，统一理解“端口”“冻结模块”“qstr”“流对象”等概念
- 给出在资源受限环境下的性能与内存优化建议，以及包管理与部署实践

该文档基于仓库中的官方中文参考文档整理，适用于ESP32/ESP32-S3系列mPython板型及同类MicroPython平台。

**章节来源**
- [docs/docs/zh_CN/reference/index.rst:1-20](../../../products/mpython/reference/index.rst)

## 核心业务流程
- 学习路径
  - 从语法总览入手，了解MicroPython对Python 3.4的覆盖范围
  - 通过REPL快速验证语法与API行为
  - 结合“微控制器上的MicroPython”指南进行内存与性能调优
  - 使用upip进行包管理，必要时将第三方库冻结到固件中
- 开发流程
  - 编写Python脚本或模块
  - 在Unix端口或目标设备上进行调试与测试
  - 针对资源受限场景进行冻结打包与部署
  - 运行后监控内存与GC行为，必要时调整阈值与调用时机

```text
flowchart TD
A["开始"] --> B["阅读语法总览<br/>确认语言特性边界"]
B --> C["使用REPL交互式验证"]
C --> D{"是否涉及I/O或外设?"}
D -- 否 --> E["继续业务逻辑开发"]
D -- 是 --> F["查阅constrained指南<br/>优化内存与IO"]
F --> G["性能分析与调优"]
G --> H{"是否需要第三方库?"}
H -- 否 --> I["完成开发与测试"]
H -- 是 --> J["使用upip安装或交叉安装"]
J --> K{"是否低内存设备?"}
K -- 是 --> L["将依赖冻结为字节码"]
K -- 否 --> M["直接部署到文件系统"]
L --> N["构建并烧录固件"]
M --> N
N --> O["运行与监控(GC/内存)"]
O --> P["结束"]
```

[无图表来源；该图为概念性流程图]

## 功能模块清单
- 语言与运行时
  - 语法与语义：遵循Python 3.4选择特性，大部分与CPython一致
  - REPL：自动缩进、自动补全、粘贴模式、软复位、原始模式、特殊变量_
  - 内存与GC：堆分配、碎片化、gc.collect()、阈值控制、micropython.mem_info()
  - 字符串与驻留：qstr机制、字符串比较优化、interned string
- 性能与优化
  - const()常量替换、缓存对象引用、避免重复创建对象
  - 缓冲区与memoryview、数组与bytes/bytearray优先
  - 本地代码发射器(@micropython.native)、Viper代码发射器(@micropython.viper)
  - 直接访问硬件寄存器（如stm模块）
- 包管理与部署
  - upip包管理器、跨平台交叉安装、冻结字节码
  - 应用资源访问（pkg_resources.resource_stream）
- 术语与概念
  - baremetal/board/MCU/port/MicroPython Unix port/stream/upip等

**章节来源**
- [docs/docs/zh_CN/reference/repl.rst:1-180](../../../products/mpython/reference/repl.rst)
- [docs/docs/zh_CN/reference/constrained.rst:1-341](../../../products/mpython/reference/constrained.rst)
- [docs/docs/zh_CN/reference/speed_python.rst:1-266](../../../products/mpython/reference/speed_python.rst)
- [docs/docs/zh_CN/reference/packages.rst:1-314](../../../products/mpython/reference/packages.rst)
- [docs/docs/zh_CN/reference/glossary.rst:1-88](../../../products/mpython/reference/glossary.rst)

## 数据与状态
- 内存模型
  - 对象分配自固定大小堆，垃圾回收自动触发并可手动调用gc.collect()
  - 可通过gc.threshold()调整触发阈值，减少长延迟与碎片化
- 字符串与标识符
  - qstr驻留：多次出现的字符串仅存储一次，提升比较与查找效率
  - interned string：通过唯一标识引用而非地址进行比较，节省时间与空间
- 冻结与资源
  - 冻结模块/字节码：将源码或字节码嵌入固件，降低RAM占用，无需文件系统
  - 应用资源：通过pkg_resources.resource_stream访问二进制资源，支持无文件系统场景

```text
graph TB
subgraph "运行时"
GC["垃圾回收器"]
HEAP["堆(固定大小池)"]
QSTR["qstr驻留表"]
end
subgraph "编译/部署"
SRC["Python源码"]
BYTE["字节码(.mpy)"]
ROM["固件ROM/Flash"]
end
SRC --> BYTE
BYTE --> ROM
ROM --> QSTR
HEAP --> GC
QSTR --> |"字符串比较/查找"| 应用["应用程序"]
GC --> |"回收/阈值控制"| HEAP
```

[无图表来源；该图为概念性数据与状态关系图]

**章节来源**
- [docs/docs/zh_CN/reference/constrained.rst:219-341](../../../products/mpython/reference/constrained.rst)
- [docs/docs/zh_CN/reference/packages.rst:144-201](../../../products/mpython/reference/packages.rst)
- [docs/docs/zh_CN/reference/glossary.rst:36-42](../../../products/mpython/reference/glossary.rst)

## 关键约束与边界
- 语言版本与特性
  - 以Python 3.4为基准，部分更高版本特性可能不可用
  - 差异主要集中于标准库、类型与少量语言级功能
- 标准库差异示例
  - sys.implementation属性在MicroPython中仅实现必要最小集合
  - sys.path等属性在不同端口的可用性存在差异
- 资源限制
  - RAM与闪存有限，需避免频繁创建对象与字符串拼接
  - 推荐使用预分配缓冲、bytes/bytearray、const常量、冻结模块
- 包管理兼容性
  - upip与CPython pip不兼容；MicroPython包格式针对低内存优化
  - 低内存设备推荐交叉安装并冻结字节码，避免运行时编译与文件系统依赖

```text
flowchart TD
Start(["开始"]) --> CheckLib["检查所需标准库"]
CheckLib --> Diff{"是否存在CPython差异?"}
Diff -- 是 --> Adapt["适配MicroPython实现<br/>或使用替代方案"]
Diff -- 否 --> Proceed["继续开发"]
Proceed --> MemCheck{"是否低内存设备?"}
MemCheck -- 是 --> Freeze["考虑冻结依赖/字节码"]
MemCheck -- 否 --> DeployFS["部署到文件系统"]
Freeze --> Build["构建固件并烧录"]
DeployFS --> Run["运行与测试"]
Build --> Run
Run --> End(["结束"])
```

[无图表来源；该图为概念性决策流程图]

**章节来源**
- [docs/docs/zh_CN/reference/index.rst:4-9](../../../products/mpython/reference/index.rst)
- `docs/docs/zh_CN/differences/index_template.txt:1-11`
- [esp32s3/docs/5_api/library/pythonStd/sys.rst:74-114](../../../products/mpython-s3/5_api/library/pythonStd/sys.rst)
- [docs/docs/zh_CN/reference/packages.rst:39-70](../../../products/mpython/reference/packages.rst)

## 术语表
以下为仓库中已定义的关键术语（节选），便于统一理解：
- baremetal：无完整操作系统的系统，如MCU；MicroPython通过REPL充当用户态OS
- board：PCB板，常指特定MCU型号或MicroPython port对应的板型
- callee-owned tuple：由内置函数返回的元组，生命周期受调用方控制，用于内存优化
- CPython：Python参考实现，其他实现（含MicroPython）与其存在差异
- GPIO/GPIO port：通用输入/输出及其端口分组
- interned string：实习字符串，通过唯一标识引用，比较更高效
- MCU：微控制器，资源受限但体积小功耗低
- micropython-lib：独立于MicroPython核心的标准库子集项目
- MicroPython port：针对不同系统/板型的移植实现
- MicroPython Unix port：面向POSIX系统的端口，用于开发与测试
- port：port或GPIO port的简称
- stream：类文件对象，提供顺序读写接口
- upip：MicroPython包管理器，功能较pip精简

**章节来源**
- [docs/docs/zh_CN/reference/glossary.rst:7-88](../../../products/mpython/reference/glossary.rst)